<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Background project discovery</title>
  <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</head>
<body text="#000000" bgcolor="#FFFFFF">

<table width="100%">
<tr><td style="background:#0080C0"><b><span style="color:white">Design Overview</span></b></td></tr>
</table>
 
<h1>Background project discovery</h1>
<font size="-1">Last modified: November 12, 2004</font> 
<h3>The Problem</h3>
<p>
Projects are often created in Eclipse whose contents already exist on a
local disk.  For example, a user checks out project contents from a repository,
or unzips some contents into their file system, and then performs either
<b>File &gt; Import &gt; Existing Project</b> or <b>File &gt; New &gt; Project</b>
to create a project on that existing location.  When the new project is opened,
the Eclipse workspace automatically performs a refresh (<tt>IResource#refreshLocal</tt>)
to discover the contents on disk and create a corresponding project representation
in memory.
</p>
<p>
For very large projects, or for projects stored on a locally mounted network drive,
this refresh operation on project creation can take a long time.  In some scenarios,
users have reported times of nearly ten minutes for this project discovery to occur.
During this time, the UI is typically blocked by the project creation or import wizard
dialog, and Eclipse becomes unusable until the refresh completes. There is no
technical reason to block the user from continuing to browse and edit other
files while this project creation is occurring.
</p>
<h3>The Solution</h3>
<p>
Support has been added in the 3.1 I20041116 build to allow background refreshing
of projects when they are opened for the first time.  Refreshing does not occur
in the background by default, since this would be a breaking change for headless
Eclipse applications or plug-ins that assume the refresh is completed as soon as
the project opens. To enable background refresh, the new <tt>IResource#BACKGROUND_REFRESH</tt>
update flag should be passed to the <tt>IProject#open(int, IProgressMonitor)</tt> method.
This flag only has effect when a project is opened for the first time.
</p>
<p>
When the flag is specified, a background job is started when the project opens.
This job searches for differences between the local file system and the in-memory
project, and refreshes resources as they are discovered.  This is implemented using
a queue that refreshes the project tree in breadth-first order. When a plug-in tries
to programmatically access a resouce that has not yet been refreshed, for
example by calling <tt>IContainer#members</tt> on a folder whose children
have not been refreshed, that folder is moved to the front of the refresh queue. In
this way, the refresh job tries to be smart about refreshing the resources that are
needed as soon as possible. For example, if the user expands an unrefreshed folder in the
Navigator view, there will initially be no children.  In the background, the folder will
be refreshed immediately, and the next resource delta will tell the Navigator what
children need to be added.  The effect is a very short delay between expanding a folder
and the children appearing in the tree. 
</p>
<h3>Action Required</h3>
<p>
Project creation and import wizards that create projects against existing contents
on disk should switch to the use the new <tt>IResource#BACKGROUND_REFRESH</tt>
update flag when opening projects for the first time.  Wizards that create projects
directly from other sources, such as zip files or repositories, do not need to specify 
this flag. Note that the <tt>open</tt> method optimizes these cases, so the 
background refresh flag will have no effect when creating a project with no existing
local contents, or when opening a project that has been opened before.  It is generally
safe to always specify the background refresh flag in project creation wizards.
</p>
</body>
</html>